/*  ------------------------------------------------------------------------
	NQ Common Services Library
	
	Homepage: http://www.awzhome.de/
	------------------------------------------------------------------------
	
	The contents of this file are subject to the Mozilla Public License
	Version 1.1 (the "License"); you may not use this file except in
	compliance with the License. You may obtain a copy of the License at
	http://www.mozilla.org/MPL/
	
	Software distributed under the License is distributed on an "AS IS"
	basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
	License for the specific language governing rights and limitations
	under the License.
   
	The Original Code is code of NQ Common Services Library.

	The Initial Developer of the Original Code is Andreas Weizel.
	Portions created by the Initial Developer are
	Copyright (C) 2006-2012 Andreas Weizel. All Rights Reserved.
	
	Contributor(s): (none)
	
	Alternatively, the contents of this file may be used under the terms
	of the GNU General Public License Version 2.0 or later (the "GPL"),
	or the GNU Lesser General Public License Version 2.1 or later (the
	"LGPL"), in which case the provisions of the GPL or the LGPL are
	applicable instead of those above. If you wish to allow use of your
	version of this file only under the terms of the GPL or the LGPL and
	not to allow others to use your version of this file under the MPL,
	indicate your decision by deleting the provisions above and replace
	them with the notice and other provisions required by the GPL or the
	LGPL. If you do not delete the provisions above, a recipient may use
	your version of this file under the terms of any of the MPL, the GPL
	or the LGPL.
	------------------------------------------------------------------------
*/

using AWZhome.NQ.Core;
using System;

namespace AWZhome.NQ.CommonServices
{
	/// <summary>
	/// Interface for services managing the containers of an NQ-based application.
	/// </summary>
	public interface IContainerManager : INQCollectionService<string, IContainer>
	{
		/// <summary>
		/// Returns the name of the default main container.
		/// </summary>
		string MainContainerName
		{
			get;
		}

		/// <summary>
		/// Returns the registered service interface of the service,
		/// which is used to create the default main container.
		/// </summary>
		System.Type MainContainerService
		{
			get;
		}

		/// <summary>
		/// Creates a new container with the given name.
		/// </summary>
		/// <param name="containerName">Name of the created container.</param>
		/// <returns>Instance of the created container service.</returns>
		/// <remarks>
		/// <para>
		/// The container name is used to save and restore specific settings for a container.
		/// </para>
		/// <para>
		/// This version of the method uses
		/// <see cref="AWZhome.NQ.CommonServices.NQCommonServices.MainContainer">NQCommonServices.MainContainer</see>
		/// as the default container service.
		/// </para>
		/// <para>
		/// If the requested container is already open, its window is brought to foreground
		/// and its existing instance is returned.
		/// </para>
		/// </remarks>
		IContainer CreateContainer(string containerName);

		/// <summary>
		/// Creates a new container with the given name using a specific
		/// container service.
		/// </summary>
		/// <param name="containerService">Registered interface of the container service.</param>
		/// <param name="containerName">Name of the created container.</param>
		/// <returns>Instance of the created container service.</returns>
		/// <remarks>
		/// <para>
		/// The container name is used to save and restore specific settings for a container.
		/// </para>
		/// <para>
		/// If the requested container is already open, its window is brought to foreground
		/// and its existing instance is returned.
		/// </para>
		/// </remarks>
		IContainer CreateContainer(Type containerService, string containerName);

		/// <summary>
		/// Shows a view and automatically chooses a container for it.
		/// </summary>
		/// <param name="currentContainer">
		/// Instance of the current container,
		/// from that the view is originally open.
		/// Can be <c>null</c>.</param>
		/// <param name="view">Instance of the view that has to be shown.</param>
		/// <remarks>
		/// The container selection is dependent on the container settings. If
		/// a protocol (type of session) is set for a container and the view
		/// is bound to such a session, the view is opened in that container. If
		/// the view is bound to a specific container, then the view is also opened in this
		/// container. Container that are not open already are opened automatically.
		/// If there are no special settings for the view or the view's session, the container
		/// passed in <paramref name="currentContainer">currentContainer</paramref> is used, or
		/// the default main container, when <paramref name="currentContainer">currentContainer</paramref>
		/// is <c>null</c>.
		/// </remarks>
		void ShowView(IContainer currentContainer, IView view);

		/// <summary>
		/// Generates a unique name for a new view.
		/// </summary>
		/// <param name="view">View to generate the name for.</param>
		/// <returns>Generated name.</returns>
		/// <remarks>
		/// This method can be used by views on initialization.
		/// </remarks>
		string GenerateViewName(IView view);

		/// <summary>
		/// Registers a main window (usually a top level window of a container), when
		/// it's opened.
		/// </summary>
		/// <param name="windowObject">
		/// The window object, for example a <see cref="System.Windows.Forms.Form">Form</see>
		/// object in Windows Forms or a <see cref="System.Windows.Window">Window</see> object
		/// in WPF.
		/// </param>
		void RegisterGUIWindow(object windowObject);

		/// <summary>
		/// Unregisters a main window (usually a top level window of a container), when
		/// it's closed.
		/// </summary>
		/// <param name="windowObject">
		/// The window object, for example a <see cref="System.Windows.Forms.Form">Form</see>
		/// object in Windows Forms or a <see cref="System.Windows.Window">Window</see> object
		/// in WPF.
		/// </param>
		/// <remarks>
		/// The application is closed when the last window is unregistered.
		/// </remarks>
		void UnregisterGUIWindow(object windowObject);

		/// <summary>
		/// Starts the message loop for the application. This is necessary to keep
		/// a GUI application open and process input events.
		/// </summary>
		void EnterMessageLoop();

		/// <summary>
		/// Ends a GUI application.
		/// </summary>
		void EndGUIApplication();
	}
}
